﻿/*!
 * Copyright (c), 上海沃恩信息科技有限公司.
 * All rights reserved.
 * Licensed under BSD (https://www.pittypat.work/bsd.html).
 */

using System.Threading.Tasks;

namespace Pittypat
{
    /// <summary>
    /// 提供用户登录、注销、权限检查工作以及加载导航列表等功能。
    /// </summary>
    /// <remarks>
    /// 通过实现 <see cref="IAuthorityService"/> 接口，开发者不必自己从头实现用户的登录、注销、权限检查以及导航功能。
    /// <see cref="IAuthorityService"/> 支持最终用户通过 "~/user/login"、"~/user/logout"、"~/user/info"、"~/user/navlist" 进行登录、注销、获取用户信息以及获取导航列表。
    /// </remarks>
    public interface IAuthorityService
    {
        /// <summary>
        /// 异步获取当前系统在目标授权服务中的系统令牌。
        /// </summary>
        /// <param name="systemId">系统的 Id。当前系统在目标服务中注册的 Id。</param>
        /// <param name="systemKey">系统的密钥。当前系统获取访问目标服务令牌时需要提供的密钥。</param>
        /// <param name="progress">跟踪和汇报异步操作的进度。</param>
        /// <returns>系统令牌。</returns>
        /// <remarks>
        /// 如果当前系统使用来自其他服务商的授权认证，则当前系统可能需要事先在目标服务商中进行注册，访问目标服务可能需要相应的系统令牌。
        /// </remarks>
        Task<string> GetSystemTokenAsync(string systemId, string systemKey, IAsyncProgress progress);

        /// <summary>
        /// 异步使用指定的用户名和密码登录当前系统。
        /// </summary>
        /// <param name="systemToken">此前已经通过 GetSystemToken 获取到的系统令牌。</param>
        /// <param name="loginName">用户登录名称。</param>
        /// <param name="password">用户登录密码的明文。</param>
        /// <param name="progress">跟踪和汇报异步操作的进度。</param>
        /// <returns>登录结果，使用 LoginResult.IsAnonymous 判断是否匿名用户。</returns>
        Task<LoginResult> LoginAsync(string systemToken, string loginName, string password, IAsyncProgress progress);

        /// <summary>
        /// 异步注销指定令牌的用户。
        /// </summary>
        /// <param name="systemToken">此前已经通过 GetSystemToken 获取到的系统令牌。</param>
        /// <param name="userToken">要注销的用户的用户令牌。</param>
        /// <param name="progress">跟踪和汇报异步操作的进度。</param>
        /// <returns>异步任务。</returns>
        Task LogoutAsync(string systemToken, string userToken, IAsyncProgress progress);

        /// <summary>
        /// 异步验证指定的用户是否对指定路径的功能具有权限。
        /// </summary>
        /// <param name="systemToken">此前已经通过 GetSystemToken 获取到的系统令牌。</param>
        /// <param name="userToken">用户令牌。</param>
        /// <param name="funcPath">目标功能的完整路径。当传递空引用或空字符串时，用于返回指定令牌的用户的用户信息。</param>
        /// <param name="progress">跟踪和汇报异步操作的进度。</param>
        /// <returns>返回作为验证结果的用户和授权信息，如果返回空引用，则使用未授权的匿名用户。</returns>
        Task<Permission> DemandAsync(string systemToken, string userToken, string funcPath, IAsyncProgress progress);

        /// <summary>
        /// 异步加载指定用户拥有权限的所有 App 和模块的列表，也就是导航列表。
        /// </summary>
        /// <param name="systemToken">此前已经通过 GetSystemToken 获取到的系统令牌。</param>
        /// <param name="userToken">用户令牌。</param>
        /// <param name="progress">跟踪和汇报异步操作的进度。</param>
        /// <returns>返回指定用户拥有权限的 App 和模块的列表。</returns>
        Task<NavList> NavListAsync(string systemToken, string userToken, IAsyncProgress progress);
    }
}
